package jblip.resources;

import java.io.Serializable;

/**
 * Interface for various media resources: pictures, recordings and videos.
 * 
 * <p>
 * <code>Media</code> represents user generated data information, but not the
 * data itself. You should create your own class for handling it.
 * </p>
 * 
 * @author Krzysztof Sroka
 * @since 0.2
 */
public interface Media extends Serializable {

  /**
   * Specifies type of content in media resources.
   * 
   * @author Krzysztof Sroka
   * @since 0.2
   */
  public static enum MediaType {
    /** Picture (image) media resource type */
    PICTURE,
    /** Recording (audio) media resource type */
    RECORDING,
    /** Movie (video) media resource type */
    MOVIE,
  }

  /**
   * Get media's ID.
   * 
   * <p>
   * Media's ID is a unique integer number describing it, so it can be used as a
   * key in various caching classes.
   * </p>
   * 
   * @return ID of this resource.
   */
  Integer getID();

  /**
   * Gets URL of this media resource.
   * 
   * @return URL of this media resource.
   */
  String getURL();

  /**
   * Gets path to the update associated with this media resource.
   * 
   * <p>
   * {@link Update} path is an optional field provided in only several server
   * responses, only if such a path can't be deducted from client's query or
   * from an external resource.
   * </p>
   * 
   * @see #getUpdate()
   * @return path to the Update resource associated with this content.
   */
  String getUpdatePath();

  /**
   * Gets update associated with this media resource.
   * 
   * <p>
   * This field represents an optional data provided by server response,
   * extended from the associated update number.
   * </p>
   * 
   * @see #getUpdatePath()
   * @return Update resource associated with this media.
   */
  Update getUpdate();

  /**
   * Returns type of this media resource.
   * 
   * @return Type of this media resource.
   */
  MediaType getType();
}